Add recipes/token-optimization.md: a ranked list of token-saving tips
for AI coding assistants (measure first, trim CLAUDE.md, caveman,
RTK/SNIP, CLI over MCP, progressive disclosure, compact, model routing,
cap thinking), each tip in the new template format with a concrete
example and an official link verified to exist. Register it in the
recipes index.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…late

Move the recipe authoring rules out of the template's HTML comment into
references/recipe-contract.md, cited by SKILL.md and upsert. The template
keeps only the scaffold.

- Steps heading carries the goal ("## Steps to <outcome>") and each step
  opens with an emoji.
- Step how-bullets follow where-it-is -> install-from-URL -> how-to-use,
  benefit-first and filler-free.
- "## Why" is short, keyword-led, and bold.
- SKILL.md description is shorter and high-level, triggered on
  "recipe" / "cook" / "/cook".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The description contained an unquoted "sheets: list" colon, which YAML
parses as a mapping value and rejects ("mapping values are not allowed
here"), breaking the skill's frontmatter. Replace the colon with a dash.
The bug pre-dated this branch (same colon on main).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… cook

Review feedback on the cook skill, plus the new includes convention:

- Recipe template drops the Time field, groups steps under three level
  subheadings (Beginner / Intermediate / Expert), and aligns the Level
  enum to Expert.
- upsert now runs `research` (03) first for any new or substantial
  recipe and drafts only from its verified results, never from memory —
  the "always research" rule was being skipped as a routing note.
- Apply R13 (explicit, scoped includes): the action-specific research
  aids move out of SKILL.md and are cited from 03-research in fenced
  blocks; refine-goal-checklist is renamed research-goal-checklist;
  SKILL.md lists only the global recipe-template and recipe-contract.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Level grouping was effectively mandatory. Make the contract state it is
optional: group steps under Beginner/Intermediate/Expert only when the
recipe spans difficulty levels and grouping helps; a short or
single-level recipe lists its steps directly. Relax the upsert Test
accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Align the recipe with references/recipe-contract.md: drop the Time row
(no longer in the template), name the section "Steps to <outcome>" instead
of a bare Steps, remove the "ranked by impact" filler line, and give each
step how-bullets plus a concrete example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The recipe opens with a plain description sentence, no "Goal:" label.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Rules extracted from the token-optimization recipe review:

- A recipe opens with the H1 title then one plain description sentence —
  no "Goal:" label, no blockquote, no metadata table. list/upsert parse
  that sentence; the index becomes `| Recipe | Description |` (Level was
  dropped, level now lives only in the optional subheadings).
- One step = one action; never bundle several tools or commands under a
  single heading.
- Every step's example shows real command output (from docs or by
  running it); the research playbook now requires capturing a real
  example and marking interactive output for the human to paste.
- `## Why` is one idea per line.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace the fabricated text output with the tool's official dashboard
screenshot (cost by token type makes "cache reads dominate" visible).
The slash-command placeholders now ask for a screenshot of the real
output.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

A real screenshot or GIF is unfakeable, faithful, and credible, where a
text example can be approximated (the failure we hit). Make the contract
and the research playbook prefer an image that matches the action —
e.g. a tool's official screenshot — falling back to real text output
only when no image exists.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- caveman: show its real `/caveman` invocation (and modes), not just a
  before/after.
- RTK: a Mermaid diagram of the proxy flow + the real `rtk <command>`
  syntax (was a wrong `rtk proxy …`) and the README's own 200->10 token
  saving.
- CLI vs MCP: a comparison table instead of prose.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

From the token-optimization review:

- Show how to invoke a tool (its real command or slash invocation).
- Reuse the canonical example from the tool's own site or README, never
  an invented one.
- A "prefer X over Y" step uses a comparison table, not prose.
- A structural or flow concept (proxy, pipeline, architecture) gets a
  small Mermaid diagram.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace the invented caveman before/after with the verbatim example from
its README (rule F: reuse the tool's own canonical example).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Actions are numbered lists; descriptions are prose (no description-bullets).
- settings.json shown as valid JSON, not a bash fragment.
- RTK Mermaid uses concrete values (cargo test ~25k -> ~2.5k tokens).
- CLI vs MCP notes MCP tool/context selection (cheaper, still slower).
- Step 10 reworded plainly ("load knowledge on demand").
- Drop the weak Verify and the redundant Related; add a short conclusion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ntract

From the token-optimization review:

- Actions are a numbered list; descriptions and indications are prose,
  never bullets.
- A Mermaid diagram carries concrete example values.
- A config example uses the file's real syntax (valid JSON for
  settings.json, valid YAML for frontmatter, ...).
- Reuse a tool's canonical example captured verbatim — never a paraphrase
  or on the strength of a summary that one exists.
- No `## Related` section (links live inline); `## Verify` is optional;
  recipes may end with a short conclusion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Step 10 now audits which skills/tools run via `Ctrl+O` (toggles the
  detailed transcript), instead of the vaguer "load on demand".
- Step 11 routes by difficulty with the real `model:` frontmatter field
  on a skill or agent (haiku/sonnet/opus/inherit) — example agent pinned
  to haiku.

Both verified against the official Claude Code docs (interactive-mode,
skills, sub-agents).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

A recipe is often a human tutorial, not an agent-runnable procedure. So
apply now reads the recipe, classifies each step agent-doable vs
human-only, and asks the user what to do before any change — then runs
the chosen agent-doable steps and reports the human-only ones.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

From a research pass, all verified against official Claude Code docs:

- Plan mode (Shift+Tab ×2) — avoid execution-phase rework.
- `/clear` between tasks — drop stale context instead of re-billing it.
- Deny reads (`permissions.deny`) — keep vendor/dist/secrets out of
  context; the official answer to the unshipped `.claudeignore`.
- Subagent offload — run high-volume ops in an isolated context.
- Protect cache hits — avoid mid-task model/MCP/effort switches that
  invalidate the cache (closes the loop on "cache reads dominate").

Also fold the built-in `outputStyle: concise` into the "talk less" step.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>